Skip to main content

Batch Integration - Body Types & Examples

This document provides comprehensive examples of all body types accepted by the GroupLink API for batch data integration configuration.

Overview​

The GroupLink API accepts different storage configuration types through the type parameter. Each type requires specific credentials in the data field.

Supported Storage Types​

  1. AWS S3 (s3_identity)
  2. Azure Blob Storage (azure_identity)
  3. Google Cloud Storage (gcs_identity)
  4. API Token (api_token_identity)

1. AWS S3 Configuration​

Request Body Structure​

{
  "namespace": "batch",
  "type": "s3_identity",
  "data": {
    "access_key": "AKIAIOSFODNN7EXAMPLE",
    "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "end_point": "https://s3.amazonaws.com",
    "region": "us-east-1"
  }
}

cURL Example​

curl -X 'PATCH' 'https://grouplink-api.apidatasafe.com/organization-vault' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR-ACCESS-TOKEN' \
  -d '{
    "namespace": "batch",
    "type": "s3_identity",
    "data": {
      "access_key": "AKIAIOSFODNN7EXAMPLE",
      "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
      "end_point": "https://s3.amazonaws.com",
      "region": "us-east-1"
    }
  }'

Swagger Example​

In Swagger UI at GroupLinkAPI OrganizationVault:

  1. Navigate to /organization-vault PATCH endpoint
  2. Click "Try it out"
  3. Use this request body:
{
  "namespace": "batch",
  "type": "s3_identity",
  "data": {
    "access_key": "YOUR_AWS_ACCESS_KEY",
    "secret_key": "YOUR_AWS_SECRET_KEY",
    "end_point": "https://s3.amazonaws.com",
    "region": "sa-east-1"
  }
}

Example of creating a bucket and access key on AWS: Bucket on AWS to receive files

2. Azure Blob Storage Configuration​

Request Body Structure​

{
  "namespace": "batch",
  "type": "azure_identity",
  "data": {
    "tenant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "client_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "client_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "connection_string": "https://AccountName.dfs.core.windows.net/bucket-name"
  }
}

cURL Example​

curl -X 'PATCH' 'https://grouplink-api.apidatasafe.com/organization-vault' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR-ACCESS-TOKEN' \
  -d '{
    "namespace": "batch",
    "type": "azure_identity",
    "data": {
      "tenant_id": "12345678-1234-1234-1234-123456789012",
      "client_id": "87654321-4321-4321-4321-210987654321",
      "client_secret": "MySecretValue123",
      "connection_string": "https://myaccount.dfs.core.windows.net/my-container"
    }
  }'

Swagger Example​

{
  "namespace": "batch",
  "type": "azure_identity",
  "data": {
    "tenant_id": "TENANT-123",
    "client_id": "12345",
    "client_secret": "G4UL3S",
    "connection_string": "https://AccountName.dfs.core.windows.net/bucket-name"
  }
}

3. Google Cloud Storage Configuration​

Request Body Structure​

{
  "namespace": "batch",
  "type": "gcs_identity",
  "data": {
    "credentials_json": "{\"type\":\"service_account\",\"project_id\":\"example-project\",\"private_key_id\":\"...\",\"private_key\":\"...\"}",
    "project_id": "my-project-123456"
  }
}

cURL Example​

curl -X 'PATCH' 'https://grouplink-api.apidatasafe.com/organization-vault' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR-ACCESS-TOKEN' \
  -d '{
    "namespace": "batch",
    "type": "gcs_identity",
    "data": {
      "credentials_json": "{\"type\":\"service_account\",\"project_id\":\"my-project\",\"private_key_id\":\"key123\",\"private_key\":\"-----BEGIN PRIVATE KEY-----\\nMIIE...\\n-----END PRIVATE KEY-----\\n\",\"client_email\":\"service@my-project.iam.gserviceaccount.com\",\"client_id\":\"123456789\"}",
      "project_id": "my-project-123456"
    }
  }'

Swagger Example​

{
  "namespace": "batch",
  "type": "gcs_identity",
  "data": {
    "credentials_json": "{\"type\":\"service_account\",\"project_id\":\"example-project\",\"private_key_id\":\"...\",\"private_key\":\"...\"}",
    "project_id": "my-project-123456"
  }
}

Note: The credentials_json must be a stringified JSON object (content of the JSON file from Google Cloud Console). Make sure to escape quotes properly.

Request Body Structure​

{
  "namespace": "batch",
  "type": "api_token_identity",
  "data": {
    "token": "sk-1234567890abcdef"
  }
}

cURL Example​

curl -X 'PATCH' 'https://grouplink-api.apidatasafe.com/organization-vault' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR-ACCESS-TOKEN' \
  -d '{
    "namespace": "batch",
    "type": "api_token_identity",
    "data": {
      "token": "your-api-token-here"
    }
  }'

Swagger Example​

{
  "namespace": "batch",
  "type": "api_token_identity",
  "data": {
    "token": "sk-1234567890abcdef"
  }
}

Field Descriptions​

Common Fields​

FieldTypeRequiredDescription
namespacestringYesNamespace to organize vault entries (e.g., "batch")
typestringYesType of storage: s3_identity, azure_identity, gcs_identity, or api_token_identity
dataobjectYesCredentials object (structure varies by type)

AWS S3 Credentials (s3_identity)​

FieldTypeMax LengthDescription
access_keystring2048Access key (user ID) of an account in the S3 service
secret_keystring2048Secret key (password) of an account in the S3 service
end_pointstring (URL)2048URL of the object storage service
regionstring100AWS Region on the properties of your bucket

Azure Credentials (azure_identity)​

FieldTypeMax LengthDescription
tenant_idstring2048The Azure Active Directory tenant (directory) ID
client_idstring2048The client (application) ID of an App Registration in the tenant
client_secretstring2048A client secret that was generated for the App Registration
connection_stringstring (URL)2048Account connection string or a SAS connection string of an Azure storage account

Google Cloud Storage Credentials (gcs_identity)​

FieldTypeMax LengthDescription
credentials_jsonstring (JSON)10240Google Service Account Credentials JSON (content of the JSON file)
project_idstring100Google Project ID

API Token Credentials (api_token_identity)​

FieldTypeMax LengthDescription
tokenstring1024Generic authentication token

Response Format​

All successful requests return the ID of the created credential:

{
  "id": "credential-uuid-here"
}

The namespace used must be informed when activating the integration.

Important: It will not be possible to view the complete data after it has been imported. Data is encrypted using AES 256 GCM at the application/database layer and again all data is saved with LUKS at rest on the database server.

API Documentation​

For complete API documentation, please refer to:

Next Steps​